Everything For A Hacker/19990506-[HACK].iso/HEXEDIT/SOCKSPY/GUIDE.TXT

Text File | 1997-02-08 | 26KB | 596 lines

SocktSpy/32... A Trace/Debug utility for Winsock applications

1.    Introduction

    1.1    Socket Spy Description
    1.2    Registration
    1.3    Licensing Agreement
    1.4    Warranty

2.    SocktSpy/32 System Requirements

    2.1    Operational Overview
    2.2    Linking an application with WnTch32.dll
    2.3    Launching a Winsock application from SocktSpy

3.    Installation

    3.1    Making Backups
    3.2    Installing SocktSpy/32

4.    Basic Menu Selections

    4.1    ToolBar
    4.2    Starting/Stopping the Trace
    4.3    Display Preferences
        4.3.1    Color & Font Selection
        4.3.2    WinSock API Display Options
    4.4    StatusBar

5.    Buffer Configuration

    5.1    Trace Buffer Operation
        5.1.1    Storing Send/Recv Data
        5.1.2    Displaying Send/Recv Data
    5.2    Trap Buffer Selection

6.    Browsing Captured Data

    6.1    Browse Menu Options
        6.1.1    Record Index
        6.1.2    Scrolling Operation
    6.2    Block Operations
        6.2.1    Print
        6.2.2    Copy to Clipboard
    6.3    Capture to File

7.    Using Filters

    7.1    API Command Filters
    7.2    Using WinSock Error Status Filters
    7.3    Restricting Trace to a designated socket

8.    Trap Buffer Operation

    8.1    Trigger
    8.2    Browsing the Trap Buffer

9.    Technical Support

    9.1    Contacting WinTECH


---------------------------------------------------------------------------
1.    Introduction
---------------------------------------------------------------------------
1.1    Socket Spy Description

Socket Spy is a Trace/Debugging utility designed to effectively
isolate communications problems between applications using the
Windows Sockets implementation of the internet protocol, (IP).
The Spy operates by placing itself between the application under
test and the Winsock dll responsible for interfacing to the actual
protocol stack.  As the application makes calls to the Winsock API,
the spy makes copies of all the data and makes it available for
display.  Any winsock compatible application may be traced, allowing
the user to trap and examine information as it passes through the dll.
Socket Spy uses the standard Microsoft Win32 Debugger API to trace an
applicaion, requiring no modifications to either the application nor
any installed operating system files or drivers.  You can install &
uninstall Socket Spy without effecting any other applications on your
PC.

Socket Spy is fully compatible with all Intel-based processors running
Windows 95 or Windows NT.  Trace support is available for the complete
WinSock 1.1 and Winsock 2.0 API.  Callback notifications and overlapped
operations are also tracable, providing the user with extensive data
concerning the path of execution made by an application.  Data associated
with each API call may be displayed in a variety of formats, with or
without a timestamp.

Debugging features of Socket Spy include the ability to selectively monitor
API calls based on function type or those associated with a designated
socket.  Socket Spy may also be configured to trace only those API calls
which return an error.  In addition to the normal Trace Buffer, Socket Spy
provides a configurable Trap Buffer for maintaining a 'snapshot' of sockets
activity based on the occurrence of a specified Logic Trigger.  This allows
the user to define a condition, (such as a specified error return value),
to fill the Trap Buffer with data for later evaluation.

Socket Spy may also be configured to save data directly to a disk file for
long-term capture of data.  Data may then be ported into conventional
Word Processor applications for evaluation and comparison with data obtained
from previous capture operations.



1.2    Registration of the SocktSpy/32 Application

Socket Spy is distributed as a fully functional demo application.
A 3 1/2 minute time limit is imposed after the successful launch
of an application to allow the user time to evaluate the features
and capabilities of Socket Spy.  After the demo time expires, the
application must be stopped and restarted to resume tracing.

Unregistered copies of the SocktSpy Application provide tracing
capabilities for the full Winsock 1.1 API set.  WinSock 2.0 specific
API calls are displayed as a single-line only.  All other operational
features of the demo are equivalent to the registered version.

Registration of the SocktSpy Application may be obtained at two levels.
Socket Spy/32-Lite supports tracing Winsock 1.1 API calls only, and requires
a registration fee of $39.95 be submitted to WinTECH Software.  The
Professional Edition of Socket Spy/32 supports tracing of both Winsock 1.1
and Winsock 2.0 API calls and requires a reqistration fee of $59.95



1.3    Licensing Agreement

Registered WinTECH software is protected by both United States Copyright
Law and International Treaty provisions.  Therefore, you must treat this
software just like a book with the following single exception.  WinTECH
Software authorizes you to make archival copies of the software for the
sole purpose of backing-up your software and protecting your investment
from loss.

By saying "just like a book," WinTECH means for example that this software
may be used by any number of people and may be freely moved from one
computer location to another so long as there is no possibility of it
being used at two locations at the same time.  Execution of two copies
of the same registered SocktSpy application at the same time constitutes
a Copyright violation and is expressly prohibited.

This licensing agreement does not apply to the unregistered, demo
version of SocktSpy/32 nor the Winsock interceptor dll's supplied with
the system.  WnTch32.dll & WnTch32b.dll may be distributed with a user's
application to support tracing API calls in the field, however, each
version of the SocktSpy/32 executable, (Trace/Debug Application), must
be licensed individually by the end-user.

1.4    Warranty

With respect to the physical diskette and physical documentation enclosed
herein, WinTECH Software warrants the same to be free of defects in
materials and workmanship for a period of 30 days from the date of
registration.  In the event of notification within the warranty period
of defects in material or workmanship, WinTECH will replace the defective
diskette or documentation.

WinTECH Software disclaims all other warranties, expressed or implied,
including without limitation, the warranties of merchantability and
of fitness for any purpose.  WinTECH Software assumes no liability for
damages, direct or consequential, which may result from the use of this
program.

---------------------------------------------------------------------------
2.    SocktSpy/32 System Requirements
---------------------------------------------------------------------------
2.1    Operational Overview

Socket Spy/32 is a trace/debugging system designed for developers of
WINSOCK communications applications.  It provides tracing
capabilities for monitoring API socket calls between the application
and the communications system by transparently tapping into the
messaging interaction between the two.  As protocol messages are
exchanged, they are duplicated and routed to a Trace Window for user
inspection.  SocktSpy-32 is fully compatible with both Winsock 1.1,
(WSOCK32.DLL) and Winsock 2.0, (WS2_32.DLL), executing on an Intel
based Windows 32-bit platforms, (Win'95 or NT).  The spy window displays
API calls in real-time and may be configured with various filters
and traps to isolate design problems.  SocktSpy/32 does not replace
the WinSock dll, rather it operates with the installed version of
Winsock to trap API calls using an interceptor library, (WnTch32.dll, etc.).
A valid WinSock dll must be operational with the installed communications
system for tracing with the SocktSpy/32 application.

Tracing a Winsock application generally involves launching the target
application from within the Socket Spy Window.  SocSpy32 normally operates
as a Win32 debugger, injecting the required hooking dll into the target
process and monitoring all API calls made to the winsock dll.  This technique
does not allow a process to continue running if the spy application
is terminated.

In situations where the user has access to the source code for the
application to be monitored, an import library is supplied which allows
the target to be linked directly with the hooking dll.  This allows the
target application to effectively traced, but does not make it dependant
upon the spy application.

2.2    Linking an application with WnTch32.dll

The SocktSpy system was designed for developers of Winsock compatible
applications.  WnTch32.dll is a Winsock 1.1 compatible interceptor and
debugging .dll which must be linked with the application under test to
allow tracing and monitoring of sockets API calls.  WnTch32 is not a
Wsock32 .dll.  It simply accepts API calls from an application and
forwards control to the installed Winsock while transfering copies
of all pass-thru data to the SocktSpy application for monitoring
and display.  A version of WSock32 compatible with the underlying
communications protocol must be installed on the system under test.
Furthermore, the WnTch32.dll only supports those API calls defined
by the WinSock 1.1 specification.  Some Winsock suppliers may utilize
extensions to the standard which take advantages of special
characteristics of their communications systems.  Any extensions
to the Winsock specification used by the application under test can
not be supported by the SocktSpy system, without modification to the
interceptor .dll.  (If required, special modifications may be made
by WinTECH Software to support specific vendor's enhancements to
the Winsock implementation.)

There are two ways to initiate the link with the Socet Spy interceptor
.dlls.  The first is to link in WnTch32.lib with the application during
the build process.  (WnTch32.lib would replace WSock32.lib in the
application make file.   WnTch32 effectively replaces all API functions
defined in the Winsock.h header file, so no source modules would need to
be re-compiled.)  This will insure that all sockets calls will be passed
to the interceptor .dll first and allow effective monitoring by the Spy.
A common practice is to link in WnTch32.lib for the debugging version of
an application, and WSock32.lib with the release version.  WnTch32.dll
may be freely distributed, and a user is permitted to include the spy
interceptor functionality in his own product if desired.  Each instance
of the SocktSpy itself, however, must be licensed individually.

2.3    Launching a Winsock application from SocktSpy

The second and most common way to initiate a trace operation is to
launch a Winsock compatible application from within the SocktSpy
application.  A menu selection from within the SocktSpy
application allows a third-party Winsock application to be started.
The standard Microsoft Win32 debugging API is used to control the target
application during start-up to interject the hooking dll.  Care must me
taken whenever shutting down the SocktSpy application, as any Win32
applications launched in this manner will terminate as well.

In certain situations, it may be possible for SocktSpy to launch and
monitor winsock API calls from 16-bit applications.  If the capability
exists on a given platform, a checkbox control is made available on the
launch dialog to direct SocktSpy to attemp to interject WnTch16 rather
than WnTch32.

--------------------------------------------------------------------------
3.    Installation
--------------------------------------------------------------------------
3.1    Making Backups

The distribution diskette is not copy-protected, and the registered user
may make backup copies as required.  The SocktSpy/32 application may be
moved from one PC to another so long as the basic licensing agreement
of only one copy in use at a time is maintained.  Registration information
is contained in the SocSpy32.cfg file and may not be duplicated.  Site
licenses are available for commercial users by contacting WinTECH Software.

3.2    Installing SocktSpy/32

Installation of the SocktSpy/32 Application involves simply copying the
socspy32.exe & socspy32.hlp files from the distribution diskette to a
working directory on the hard disk.  All dll's, (wntch32.dll, wntch32b.dll,
wntch16.dll, wntch16b.dll, wintech.dll, and wintech2.dll), should be copied
to the same directory as the working copy of wsock32.dll or ws2_32.dll.
After running the application for the first time, a configuration file
will be created on the working directory.  socspy32.cfg represents the
user configurable selections, (character font, filters, trigger, etc.),
in effect at the time the program terminated. These settings will be
restored the next time SocktSpy is started.


--------------------------------------------------------------------------
4.    Basic Menu Selections
--------------------------------------------------------------------------
4.1    ToolBar

Toolbar buttons provide access to the commonly used menu options defined
below:

    FILE OPEN: Fills the display buffer with the contents of a
        previously saved trace operation.

    FILE SAVEAS: Copies the displayed buffer, (trace or trap), to
        a defined disk file.

    TIMESTAMP: Include timestamp with display of each API trace
        record.

    VERBOSE: Display extended information for each API trace record.

    FILTER: Specify filtering characteristics for trace operation.

    TRAP: Enable/disable logic trap.

    START TRACE: Begin monitoring socket calls.

    STOP TRACE: Stop monitoring.

    COPY: Copy selected trace records to Windows clipboard.

    PRINT: Print selected trace records.

    ABOUT: Display copyright notice and software revision levels.


4.2    Starting/Stopping the Trace

The SocktSpy Trace Window operates in two modes.  During an active trace
operation, API calls are displayed as they occur between the application
and the Winsock.dll.  During a browsing operation, the user may scroll
back and forth through the trace buffer, switch between the trace and
trap buffers, copy & print trace records and save data to a disk file.
All message interaction between the application under test and the .dll
continue as normal during browse operations, however the spy does not
receive the information except during an active trace.  Trace operations
are controlled via two menu option/toolbar buttons (START & STOP).

4.3    Display Preferences

4.3.1    Color & Font Selection

Menu options are provided to select the font and colors used to display
the results of a trace.  Any installed font may be used to suit the
taste of the user.  Up to five colors may be selected; one for the window
background and four text pens used to display API trace records.

4.3.2    WinSock API Display Options

The display of trace records is controlled by five options accessible
from the PREFERENCES menu selection.

    TIMESTAMP: Include timestamp with display of each API trace
        record.

    VERBOSE: Display extended information for each API trace record.
        Verbose display shows arguments passed to the Winsock.dll
        for each API call as well as data buffers transfered via
        send(), sendto(), recv() & recvfrom().

    VERTICAL SPACE: Simply adds an extra CRLF after the display of
        each record on the display.

    DATA ONLY:  This option allows the display to represent only the
        data blocks passed through the socket as a result of the
        send(), sendto(), recv(), or recvfrom() API calls.  A
        description of the actual call/argument list is not
        displayed.

    DISPLAY EXTD:  This option provides additional information relative
        to certain Winsock 2.0 API calls, (QOS structures etc.).

4.4    StatusBar

The statusbar is used to represent the status of the trap buffer and
trigger during an active trace operation.  The trap buffer is cleared
whenever the trap is activated and the trace starts.  It will be filled
with an image of the trace buffer at the time the trigger event occurs.

The statusbar is also used to display the record numbers represented by
the SocktSpy display.  The index of the first record displayed in the
window and the maximum number of trace records contained in the displayed
trace buffer are depicted.


--------------------------------------------------------------------------
5.    Buffer Configuration
--------------------------------------------------------------------------

5.1    Trace Buffer Operation

As API record descriptions are received from the interceptor dll, they
are copied in their entirety to buffers dynamically allocated within
the SocktSpy.  Dll buffers are then released for re-use by WnTch32.

Memory buffers allocated by the SocktSpy trace window vary in size
depending upon the amount of data to maintain.  This is minimal for
everything except data blocks captured as a result of the send()/recv()
operations.  API call records are collected and maintained in a circular
list of buffers with new data replacing old data.  The size of the
circular list is controlled by a dialog box entry accessible from the
SocktSpy Filter Selection Dialog.  Buffer parameters may only be changed
while the SocktSpy is in a Browse mode of operation.  They may not be
changed during an active trace operation.

5.1.1    Storing Send/Recv Data

Normally, the SocktSpy application would be configured to monitor all
data passed through a socket.  In applications involving large block
transfers, it may be desirable to limit the amount of data captured
by the spy.  The user may select to only capture partial data blocks
from the send(), sendto(), recv(), & recvfron() socket calls.  This
maximizes the through-put of the application/spy/winsock interaction.


5.1.2    Displaying Send/Recv Data

The user may also elect to only display partial data block information
within the spy window.  Data block displays may be reduced to show a
"thumbprint" of the actual data collected during an real-time trace,
and subsequently expanded for a more detailed examination during browse.

5.2    Trap Buffer Selection

SoctkSpy provides a unique list of data buffers used to take a snapshot
of the normal trace buffer based on the occurrence of an event trigger.
During a trace operation, SocktSpy constantly compares API trace records
received from the interceptor dll with a trigger mask configured by
the user.  If the received data matches the trigger specification, trace
records are moved into the trap buffer and the trigger is disabled.  As
additional records are received, they will overwrite records in the trace
buffer, but the trap buffers maintain the original record descriptions
at the time of the trigger.  The trap buffer may be configured to
position the trigger in the front, middle, or back.  In other words,
the trap buffer can be setup to capture the data records immediately
preceeding the trigger, immediately after the trigger, or surrounding
the trigger.


--------------------------------------------------------------------------
6.    Browsing Captured Data
--------------------------------------------------------------------------
6.1    Browse Menu Options

Timing operation of messaging interactions between the application under
test, the communications system, and the spy application are maximized
by restricting most user menu selections to an off-line browse mode
of operation.  These include the ability to scroll the display, copy
and print operations.

6.1.1    Record Index

The display of each API record includes a buffer index designating its
position in the list.  The record index of the first record displayed
on the screen is also listed in the SocktSpy statusbar.  If the trap
buffer is being displayed, the event which triggered the capture will
have its record identifier set to [TRIGGER].

6.1.2    Scrolling Operation

Vertical scroll bar support is provided for browsing either the trace
or trap buffers.  The scrollbar is disabled, (hidden), during an active
trace.

6.2    Block Operations

6.2.1    Print

A group of API trace records may be selected for print operations by
specifying the starting and ending indexes.  Printer output of data
will conform to the same options selected for the window display,
(i.e. TIMESTAMP, VERBOSE, VERTICAL SPACE, & DATA ONLY options apply).

6.2.2    Copy to Clipboard

API records may also be copied to the Windows clipboard based on a
starting and ending record index.  Data will be copied in an ASCII
format as would be displayed on the screen.

6.3    Capture to File

API records may be captured directly to a disk file by enabling the option
available under the "File Capture" menu.  Data is written to the specified
disk file in ASCII text which may be later reviewed using any Windows text
editor.  Data is written to disk as it is displayed to the Socket Spy
Trace Window, using the same display preference selections.  There is no
limit placed upon the size of the capture file, and the user is responsible
for prudent exercise of this option.

--------------------------------------------------------------------------
7.    Using Filters
--------------------------------------------------------------------------
7.1    API Command Filters

SocktSpy provides trace support for the following WinSock API function
references:

(WinSock 1.1)

    accept()                       gethostbyaddr()
    bind()                         gethostbyname()
    closesocket()                  gethostname()
    connect()                      getprotobyname()
    getpeername()                  getprotobynumber()
    getsockname()                  getservbyname()
    getsockopt()                   getservbyport()
    htonl()
    htons()                        WSAAsyncGetHostByAddr()
    inet_addr()                    WSAAsyncGetHostByName()
    inet_ntoa()                    WSAAsyncGetProtoByName()
    ioctlsocket()                  WSAAsyncGetProtoByNumber()
    listen()                       WSAAsyncGetServByName()
    ntohl()                        WSAAsyncGetServByPort()
    ntohs()                        WSAAsyncSelect()
    recv()                         WSACancelAsyncRequest()
    recvfrom()                     WSACancelBlockingCall()
    select()                       WSACleanup()
    send()                         WSAGetLastError()
    sendto()                       WSAIsBlocking()
    setsockopt()                   WSASetBlockingHook()
    shutdown()                     WSASetLastError()
    socket()                       WSAStartup()
                                       WSAUnhookBlockingHook()

(WinSock 2.0)

    WSAAccept()
    WSACloseEvent()
    WSAConnect()
    WSACreateEvent()
    WSAEnumProtocols()
    WSAGetOverlappedResult()
    WSAHtonl()
    WSAHtons()
    WSANtohl()
    WSANtohs()
    WSARecv()
    WSARecvFrom()
    WSAResetEvent()
    WSASend()
    WSASendTo()
    WSASetEvent()
    WSASocket()

Tracing may be selectively enabled/disabled for each API event.

7.2    Using WinSock Error Status Filters

Two options are provided within the Filter Specification to capture
data using the return value from the WinSock.dll in response to a
given API call.  WSAEWOULDBLOCK is a status indication returned from
the dll in response to an API call request which cannot be immediately
completed.  This may or may not be a normal occurrence for any given
WinSock application.  A filter specification option allows all API
requests which return WSAEWOULDBLOCK to be ignored, (in terms of
the trace operation).  SocktSpy may also be configured to only monitor
API calls which return an error status from WinSock.

7.3    Restricting Trace to a designated socket

During a trace operation, multiple sockets may be active, from
one or more applications linked with the WnTch32 interceptor dll.
Monitoring of API records may be restricted to only those associated
with a given socket by specifying the socket id within the Filter
Specification.  Since the filtering characteristics of the SocktSpy
system may be changed during an active trace operation, the user may
monitor socket assignments made in real-time and selectively monitor
those of interest.


--------------------------------------------------------------------------
8.    Trap Buffer Operation
--------------------------------------------------------------------------
8.1    Trigger

As mentioned previously, the trap buffer represents a snapshot of
trace records contained in the normal trace buffer at the time of
a user defined logic trigger.  The trigger spcification may be
associated with a particular API reference, API status return value,
or data contained in a transmitted or received data block.  In the
case of an event triggered from a data block operation, the user may
specify a byte pattern and an offset from the start of the block to
begin the comparison.

8.2    Browsing the Trap Buffer

During a browsing operation, the display may be switched back and forth
between the trace buffer and trap buffer by selecting an option from
the main SocktSpy menu.  Scrolling operations, copy & print operations,
and display parameters operate identically for either buffer display.

--------------------------------------------------------------------------
9.    Technical Support
--------------------------------------------------------------------------
9.1    Contacting WinTECH

Additional information and FAQ may be found on the World-Wide-Web at:

http://www.win-tech.com

For technical questions, problems with installation and/or
operation of the SocktSpy application, or feedback concerning
enhancements or improvements, please contact:

WinTECH Software
P.O. Box 907
Lewisburg, WV  24901
[phone]

email: [e-mail]